<!DOCTYPE html>
<html>
<head>
	<!-- Global site tag (gtag.js) - Google Analytics -->
	<script async src="https://www.googletagmanager.com/gtag/js?id='UA-133422980-2"></script>
	<script>
	  window.dataLayer = window.dataLayer || [];
	  function gtag(){dataLayer.push(arguments);}
	  gtag('js', new Date());

	  gtag('config', 'UA-133422980-2');
	</script>

	<meta charset="utf-8">
	<meta http-equiv="x-ua-compatible" content="ie=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1">

	<title>
		gem5: A beginners guide to contributing 
	</title>

	<!-- SITE FAVICON -->
	<link rel="shortcut icon" type="image/gif" href="/assets/img/gem5ColorVert.gif"/>

	<link rel="canonical" href="http://localhost:4000/contributing">
	<link href='https://fonts.googleapis.com/css?family=Open+Sans:400,300,700,800,600' rel='stylesheet' type='text/css'>
	<link href='https://fonts.googleapis.com/css?family=Muli:400,300' rel='stylesheet' type='text/css'>

	<!-- FAVICON -->
	<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">

	<!-- BOOTSTRAP -->
	<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">

	<!-- CUSTOM CSS -->
	<link rel="stylesheet" href="/css/main.css">
</head>


<body>
	<nav class="navbar navbar-expand-md navbar-light bg-light">
  <a class="navbar-brand" href="/">
		<img src="/assets/img/gem5ColorLong.gif" alt="gem5" height=55px>
	</a>
  <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNavDropdown" aria-controls="navbarNavDropdown" aria-expanded="false" aria-label="Toggle navigation">
    <span class="navbar-toggler-icon"></span>
  </button>
  <div class="collapse navbar-collapse" id="navbarNavDropdown">
    <!-- LIST FOR NAVBAR -->
    <ul class="navbar-nav ml-auto">
      <!-- HOME -->
      <li class="nav-item ">
        <a class="nav-link" href="/">Home</a>
      </li>

      <!-- ABOUT -->
			<li class="nav-item dropdown ">
				<a class="nav-link dropdown-toggle" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
					About
				</a>
				<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
          <a class="dropdown-item" href="/about">About gem5</a>
          <a class="dropdown-item" href="/publications">Publications</a>
          <a class="dropdown-item" href="/governance">Governance</a>
				</div>
			</li>

      <!-- DOCUMENTATION -->
			<li class="nav-item dropdown ">
				<a class="nav-link dropdown-toggle" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
					Documentation
				</a>
				<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
					<!-- Pull navigation from _data/documentation.yml -->
					
            <a class="dropdown-item" href="/documentation">gem5 documentation</a>
					
            <a class="dropdown-item" href="/documentation/learning_gem5/introduction">Learning gem5</a>
					
            <a class="dropdown-item" href="http://doxygen.gem5.org/release/current/index.html">gem5 Doxygen</a>
					
            <a class="dropdown-item" href="/documentation/reporting_problems">Reporting Problems</a>
					
				</div>
			</li>

      <!-- EVENTS -->
			<li class="nav-item dropdown ">
        <a class="nav-link" href="/events/">Events</a>
			</li>

      <!-- CONTRIBUTING -->
      <li class="nav-item ">
        <a class="nav-link" href="/contributing">Contributing</a>
      </li>

      <!-- BLOG -->
      <li class="nav-item ">
        <a class="nav-link" href="/blog">Blog</a>
      </li>

      <!-- SEARCH -->
			<li class="nav-item ">
        <a class="nav-link" href="/search">Search</a>
      </li>
    </ul>
  </div>
</nav>

	<main>
		<br><br>
<div class="container">

  <h1 class="title">A beginners guide to contributing</h1>
  <br>
  <p>This document serves as a beginners guide to contributing to gem5. If questions
arise while following this guide, we advise consulting <a href="https://gem5.googlesource.com/public/gem5/+/refs/heads/master/CONTRIBUTING.md">CONTRIBUTING.md</a>
which contains more details on how to contribute to gem5.</p>

<p>The following subsections outline, in order, the steps involved in contributing
to the gem5 project.</p>

<h2 id="determining-what-you-can-contribute">Determining what you can contribute</h2>

<p>The easiest way to see how you can contribute to gem5 is to check our Jira
issue tracker: <a href="https://gem5.atlassian.net">https://gem5.atlassian.net</a>. From Jira you can check open
issues.</p>

<p>Browse these open issues and see if there are any which you are capable of
handling. When you find a task you are happy to carry out, verify no one else
is presently assigned, then leave a comment asking if you may assign yourself
this task (this will involve creating a Jira account). Though not mandatory, we
advise first-time contributors do this so developers more familiar with the
task may give advice on how best to implement the necessary changes.</p>

<p>Once a developers has replied to your comment (and given any advice they may
have), you may officially assign yourself the task. After this you should
change the status of the task from <code class="highlighter-rouge">Todo</code> to <code class="highlighter-rouge">In progress</code>. This helps the gem5
development community understand which parts of the project are presently being
worked on.</p>

<p><strong>If, for whatever reason, you stop working on a task, please unassign
yourself from the task and change the task’s status back to <code class="highlighter-rouge">Todo</code>.</strong></p>

<h2 id="obtaining-the-git-repo">Obtaining the git repo</h2>

<p>The gem5 git repository is hosted at <a href="https://gem5.googlesource.com">https://gem5.googlesource.com</a>.
<strong>Please note: contributions made to other gem5 repos (e.g., our GitHub mirror)
will not be considered. Please contribute to <a href="https://gem5.googlesource.com">https://gem5.googlesource.com</a>
exclusively.</strong></p>

<p>To pull the gem5 git repo:</p>

<pre><code class="language-Shell">git clone https://gem5.googlesource.com/public/gem5
</code></pre>

<h3 id="master-as-stable--develop-branch">master-as-stable / develop branch</h3>

<p>By default, the git repo will have the <code class="highlighter-rouge">master</code> branch checked-out. The
<code class="highlighter-rouge">master</code> branch is considered the gem5 stable release branch. I.e., the HEAD
of this branch contains the latest stable release of gem5. (execute <code class="highlighter-rouge">git tag</code>
on the <code class="highlighter-rouge">master</code> branch to see the list of stable releases. A particular
release may be checked out by executing <code class="highlighter-rouge">git checkout &lt;release&gt;</code>). As the
<code class="highlighter-rouge">master</code> branch only contains officially released gem5 code <strong>contributors
should not develop changes on top of the <code class="highlighter-rouge">master</code> branch</strong> they should instead
<strong>develop changes on top of the <code class="highlighter-rouge">develop</code> branch</strong>.</p>

<p>To checkout the <code class="highlighter-rouge">develop</code> branch:</p>

<pre><code class="language-Shell">git checkout --track origin/develop
</code></pre>

<p>Changes may be made on this branch to incorporate changes assigned to yourself.</p>

<p>As the develop branch is frequently updated, regularly obtain the latest
<code class="highlighter-rouge">develop</code> branch by executing:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git pull --rebase
</code></pre></div></div>

<p>Conflicts may need resolved between your local changes and new changes on the
<code class="highlighter-rouge">develop</code> branch.</p>

<h2 id="making-modifications">Making modifications</h2>

<p>Different tasks will require the project to be modified in different ways.
Though, in all cases, our style-guide must be adhered to. The full style guide
is outlined <a href="/documentation/general_docs/development/coding_style">here</a>.</p>

<p>As a high-level overview:</p>

<ul>
  <li>Lines must not exceed 79 characters in length.</li>
  <li>There should be no trailing white-space on any line.</li>
  <li>Indentations must be 4 spaces (no tab characters).</li>
  <li>Class names must use upper camel case (e.g., <code class="highlighter-rouge">ThisIsAClass</code>).</li>
  <li>Class member variables must use lower camel case (e.g.,
<code class="highlighter-rouge">thisIsAMemberVariable</code>).</li>
  <li>Class member variables with their own public accessor must start with an
underscore (e.g., <code class="highlighter-rouge">_variableWithAccessor</code>).</li>
  <li>Local variables must use snake case (e.g., <code class="highlighter-rouge">this_is_a_local_variable</code>).</li>
  <li>Functions must use lower camel case (e.g., <code class="highlighter-rouge">thisIsAFunction</code>)</li>
  <li>Function parameters must use snake case.</li>
  <li>Macros must be in all caps with underscores (e.g., <code class="highlighter-rouge">THIS_IS_A_MACRO</code>).</li>
  <li>Function declaration return types must be on their own line.</li>
  <li>Function brackets must be on their own line.</li>
  <li><code class="highlighter-rouge">for</code>/<code class="highlighter-rouge">if</code>/<code class="highlighter-rouge">while</code> branching operations must be followed by a white-space
before the conditional statement (e.g., <code class="highlighter-rouge">for (...)</code>).</li>
  <li><code class="highlighter-rouge">for</code>/<code class="highlighter-rouge">if</code>/<code class="highlighter-rouge">while</code> branching operations’ opening bracket must be on the
same line, with the closing bracket on its own line (e.g.,
<code class="highlighter-rouge">for (...) {\n ... \n}\n</code>). There should be a space between the condition(s)
and the opening bracket.</li>
  <li>C++ access modifies must be indented by two spaces, with method/variables
defined within indented by four spaces.</li>
</ul>

<p>Below is a simple toy example of how a class should be formatted:</p>

<pre><code class="language-C++">#DEFINE EXAMPLE_MACRO 7
class ExampleClass
{
  private:
    int _fooBar;
    int barFoo;

  public:
    int
    getFooBar()
    {
        return _fooBar;
    }

    int
    aFunction(int parameter_one, int parameter_two)
    {
        int local_variable = 0;
        if (true) {
            int local_variable = parameter_one + parameter_two + barFoo
                               + EXAMPLE_MACRO;
        }
        return local_variable;
    }

}
</code></pre>

<h2 id="compiling-and-running-tests">Compiling and running tests</h2>

<p>The minimum criteria for a change to be submitted is that the code is
compilable and the test cases pass.</p>

<p>The following command both compiles the project and runs our system-level
checks:</p>

<pre><code class="language-Shell">cd tests
python main.py run
</code></pre>

<p><strong>Note: These tests can take several hours to build and execute. <code class="highlighter-rouge">main.py</code> may
be run on multiple threads with the <code class="highlighter-rouge">-j</code> flag. E.g.: <code class="highlighter-rouge">python main.py run
-j6</code>.</strong></p>

<p>The unit tests should also pass. To run the unit tests:</p>

<pre><code class="language-Shell">scons build/NULL/unittests.opt
</code></pre>

<p>To compile an individual gem5 binary:</p>

<pre><code class="language-Shell">scons build/{ISA}/gem5.opt
</code></pre>

<p>where <code class="highlighter-rouge">{ISA}</code> is the target ISA. Common ISAs are <code class="highlighter-rouge">ARM</code>, <code class="highlighter-rouge">MIPS</code>, <code class="highlighter-rouge">POWER</code>,
<code class="highlighter-rouge">RISCV</code>, <code class="highlighter-rouge">SPARC</code>, and <code class="highlighter-rouge">X86</code>. So, to build gem5 for <code class="highlighter-rouge">X86</code>:</p>

<pre><code class="language-Shell">scons build/X86/gem5.opt
</code></pre>

<h2 id="committing">Committing</h2>

<p>When you feel your change is done, you may commit. Start by adding the changed
files:</p>

<pre><code class="language-Shell">git add &lt;changed files&gt;
</code></pre>

<p>Then commit using:</p>

<pre><code class="language-Shell">git commit
</code></pre>

<p>The commit message must adhere to our style. The first line of the commit is
the “header”. The header starts with a tag (or tags, separated by a comma),
then a colon. Which tags are used depend on which components of gem5
you have modified. <strong>Please refer to the <a href="https://gem5.googlesource.com/public/gem5/+/refs/heads/master/MAINTAINERS">MAINTAINERS.md</a> for
a comprehensive list of accepted tags</strong>. After this colon a short description
of the commit must be provided. <strong>This header line must not exceed 65
characters</strong>.</p>

<p>After this, a more detailed description of the commit can be added. This is
inserted below the header, separated by an empty line. Including a description
is optional but it’s strongly recommended. The description may span multiple
lines, and multiple paragraphs. <strong>No line in the description may exceed 75
characters.</strong></p>

<p>To improve the navigability of the gem5 project we would appreciate if commit
messages include a link to the relevant Jira issue/issues.</p>

<p>Below is an example of how a gem5 commit message should be formatted:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>test,base: This commit tests some classes in the base component

This is a more detailed description of the commit. This can be as long as
is necessary to adequately describe the change.

A description may spawn multiple paragraphs if desired.

Jira Issue: https://gem5.atlassian.net/browse/GEM5-186
</code></pre></div></div>

<p>If you feel the need to change your commit, add the necessary files then
<em>amend</em> the changes to the commit using:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git commit --amend
</code></pre></div></div>

<p>This will give you opportunity to edit the commit message.</p>

<h2 id="pushing-to-gerrit">Pushing to Gerrit</h2>

<p>Pushing to Gerrit will allow others in the gem5 project to review the change to
be fully merged into the gem5 source.</p>

<p>To start this process, execute:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git push origin HEAD:refs/for/develop
</code></pre></div></div>

<p>At this stage you may receive an error if you’re not registered to contribute
to our Gerrit. To resolve this issue:</p>

<ol>
  <li>Create an account at <a href="https://gem5-review.googlesource.com">https://gem5-review.googlesource.com</a>.</li>
  <li>Go to <code class="highlighter-rouge">User Settings</code>.</li>
  <li>Select <code class="highlighter-rouge">Obtain password</code> (under <code class="highlighter-rouge">HTTP Credentials</code>).</li>
  <li>A new tab shall open, explaining how to authenticate your machine to make
contributions to Gerrit. Follow these instructions and try pushing again.</li>
</ol>

<p>Gerrit will amend your commit message with a <code class="highlighter-rouge">Change-ID</code>. Any commit pushed
to Gerrit with this <code class="highlighter-rouge">Change-ID</code> is assumed to be part of this change.</p>

<h2 id="code-review">Code review</h2>

<p>Now, at <a href="https://gem5-review.googlesource.com">https://gem5-review.googlesource.com</a>, you can view the
change you have submitted (<code class="highlighter-rouge">Your</code> -&gt; <code class="highlighter-rouge">Changes</code> -&gt; <code class="highlighter-rouge">Outgoing reviews</code>). We
suggest that, at this stage, you mark the corresponding Jira issue
as <code class="highlighter-rouge">In Review</code>. Adding a link to the change on Gerrit as a comment to the
issue is also helpful.</p>

<p>Through the Gerrit portal we strongly advise you add reviewers.
Gerrit will automatically notify those you assign. The “maintainers” of the
components you have modified should be added as reviewers. These should
correspond to the tags you included in the commit header. <strong>Please consult
<a href="https://gem5.googlesource.com/public/gem5/+/refs/heads/master/MAINTAINERS">MAINTAINERS.md</a> to
see who maintains which component</strong>. As an example, for a commit with a header
of <code class="highlighter-rouge">tests,arch : This is testing the arch component</code> then the maintainers for
both <code class="highlighter-rouge">tests</code> and <code class="highlighter-rouge">arch</code> should be included as reviewers.</p>

<p>Reviewers will then review this change. There are three scores which the commit
shall be evaluated: “Code-Review”, “Maintainer”, and “Verified”.</p>

<p>Each reviewer can give a score from <code class="highlighter-rouge">-2</code> to <code class="highlighter-rouge">+2</code> to the “Code-Review” score,
where <code class="highlighter-rouge">+2</code> indicates the reviewer is 100% okay with the patch in its current
state and <code class="highlighter-rouge">-2</code> when the reviewer is certain they do not want the patch
merged in its current state.</p>

<p>Maintainers can add <code class="highlighter-rouge">+1</code> or <code class="highlighter-rouge">-1</code> to the “Maintainer” score. A <code class="highlighter-rouge">+1</code> score
indicates that the maintainer is okay with the patch.</p>

<p>When a Maintainer gives a <code class="highlighter-rouge">+1</code> our continuous integration system will process
the change. At the time of writing, the continuous integration system will run:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>scons build/NULL/unittests.opt
cd tests
python main.py run
</code></pre></div></div>

<p>If this executes successfully (i.e. the project builds and the tests pass) the
continuous integration system will give a <code class="highlighter-rouge">+1</code> to the “Verifier” score, and a
<code class="highlighter-rouge">-1</code> if it did not execute successfully.</p>

<p>Gerrit will permit a commit to be merged if at least one reviewer has given a
<code class="highlighter-rouge">+2</code> to the “Reviewer” score, one maintainer has given a <code class="highlighter-rouge">+1</code> to the
“Maintainer” score, and the continuous integration system has given a <code class="highlighter-rouge">+1</code> to
the “Verifier” score.</p>

<p>For non-trivial changes, it is not unusual for a change to receive feedback
from reviewers that they will want incorporated before giving the commit a
score necessary for it to be merged. This leads to an iterative process.</p>

<h3 id="making-iterative-improvements-based-on-feedback">Making iterative improvements based on feedback</h3>

<p>A reviewer will ask questions and post suggestions on Gerrit. You should read
these comments and answer these questions. <strong>All communications between
reviewers and contributors should be done in a polite manner. Rude and/or
dismissive remarks will not be tolerated.</strong></p>

<p>When you understand what changes are required, using the same workspace as
before, make the necessary modifications to the gem5 repo, and amend the
changes to the commit:</p>

<pre><code class="language-Shell">git commit --amend
</code></pre>

<p>Then push the new changes to Gerrit:</p>

<pre><code class="language-Shell">git push original HEAD:refs/for/develop
</code></pre>

<p>If for some reason you no longer have your original workspace, you may pull
the change by going to your change in Gerrit, clicking <code class="highlighter-rouge">Download</code> and executing
one of the listed commands.</p>

<p>When your new change is uploaded via the <code class="highlighter-rouge">git push</code> command, the reviewers will
re-review the change to ensure you have incorporated their suggested
improvements. The reviewers may suggest more improvements and, in this case,
you will have to incorporate them using the same process as above. <strong>This
process is therefore iterative, and it may therefore take several cycles until
the patch is in a state in which the reviewers are happy</strong>. Please do not
be deterred, it is very common for a change to require several iterations.</p>

<h2 id="submit-and-merge">Submit and merge</h2>

<p>Once this iterative process is complete. The patch may be merged. This is done
via Gerrit (Simply click <code class="highlighter-rouge">Submit</code> within the relevant Gerrit page).</p>

<p>As one last step, you should change the corresponding Jira issue status to
<code class="highlighter-rouge">Done</code> then link the Gerrit page as a comment on Jira as to provide evidence
that the task has been completed.</p>

<p>Stable releases of gem5 are published three times per year. Therefore, a change
successfully submitted to the <code class="highlighter-rouge">develop</code> branch will be merged into the <code class="highlighter-rouge">master</code>
branch within three to four months after submission.</p>


</div>

<!-- button to scroll to top of page -->
<button onclick="topFunction()" id="myBtn" title="Go to top">&#9651;</button>

	</main>
	<footer class="page-footer">
	<div class="container">
		<div class="row">

			<div class="col-12 col-sm-4">
				<p>gem5</p>
				<p><a href="/about">About</a></p>
				<p><a href="/publications">Publications</a></p>
				<p><a href="/contributing">Contributing</a></p>
				<p><a href="/governance">Governance</a></p>
			<br></div>

			<div class="col-12 col-sm-4">
				<p>Docs</p>
				<p><a href="/documentation">Documentation</a></p>
				<p><a href="http://gem5.org/Documentation">Old Documentation</a></p>
				<p><a href="https://gem5.googlesource.com/public/gem5">Source</a></p>
			<br></div>

			<div class="col-12 col-sm-4">
				<p>Help</p>
				<p><a href="/search">Search</a></p>
				<p><a href="/mailing_lists">Mailing Lists</a></p>
				<p><a href="https://gem5.googlesource.com/public/gem5-website/+/refs/heads/master/README.md">Website Source</a></p>
			<br></div>

		</div>
	</div>
</footer>


	<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
	<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
	<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
	<script src="https://unpkg.com/commentbox.io/dist/commentBox.min.js"></script>

	<script>
	  // When the user scrolls down 20px from the top of the document, show the button
	  window.onscroll = function() {scrollFunction()};

	  function scrollFunction() {
	      if (document.body.scrollTop > 100 || document.documentElement.scrollTop > 20) {
	          document.getElementById("myBtn").style.display = "block";
	      } else {
	          document.getElementById("myBtn").style.display = "none";
	      }
	  }

	  // When the user clicks on the button, scroll to the top of the document
	  function topFunction() {
	      document.body.scrollTop = 0;
	      document.documentElement.scrollTop = 0;
	  }

		import commentBox from 'commentbox.io';
		// or
		const commentBox = require('commentbox.io');
		// or if using the CDN, it will be available as a global "commentBox" variable.

		commentBox('my-project-id');

	</script>

</body>


</html>
